[Server][Schema] Add elicitation support for server-to-client user input requests by wachterjohannes · Pull Request #228 · modelcontextprotocol/php-sdk

wachterjohannes · 2026-01-24T21:20:11Z

Motivation and Context

This PR implements the elicitation feature from the MCP specification (2025-06-18), which allows servers to request additional information from users during tool execution via the elicitation/create method.

Elicitation enables interactive workflows where the server can:

Ask for user preferences or choices
Collect form data with validated fields
Request confirmation before performing actions

This is particularly useful for tools that need dynamic user input that can't be determined upfront.

How Has This Been Tested?

Unit tests: 87 new tests covering all elicitation classes
PHPStan: No errors at configured level
Integration testing: Tested with OpenCode PR #8243 which adds elicitation client support
- Verified book_restaurant tool with multi-field form (number, date, enum)
- Verified confirm_action tool with boolean confirmation
- Verified collect_feedback tool with rating enum and optional comments
- Tested accept, decline, and cancel user responses

Breaking Changes

None. This is a purely additive feature.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Files added

Schema definitions (src/Schema/Elicitation/):

StringSchemaDefinition - String fields with optional format (date, email, uri), minLength, maxLength
NumberSchemaDefinition - Integer/number fields with min/max validation
BooleanSchemaDefinition - Boolean checkbox fields
EnumSchemaDefinition - String enums with optional human-readable labels (enumNames)
PrimitiveSchemaDefinition - Factory for deserializing schema definitions
ElicitationSchema - Wrapper for the requestedSchema object

Request/Result (src/Schema/):

Enum/ElicitAction - User response actions (accept, decline, cancel)
Request/ElicitRequest - The elicitation/create request
Result/ElicitResult - The client's response with convenience methods (isAccepted(), isDeclined(), isCancelled())

Server changes:

ClientGateway::elicit() - Convenience method for sending elicitation requests
InitializeHandler - Now stores client capabilities in session for capability checking

Example (examples/server/elicitation/):

Complete working example with three tools demonstrating different elicitation patterns
Includes capability checking for graceful fallback when client doesn't support elicitation

Protocol details

Request format:

{
  "method": "elicitation/create",
  "params": {
    "message": "Please provide your reservation details:",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "party_size": { "type": "integer", "minimum": 1, "maximum": 20 },
        "date": { "type": "string", "format": "date" }
      },
      "required": ["party_size", "date"]
    }
  }
}

Response format:

{
  "action": "accept",
  "content": { "party_size": 4, "date": "2025-02-14" }
}

Link to the MCP Specification: https://modelcontextprotocol.io/specification/draft/client/elicitation

wachterjohannes · 2026-01-24T21:22:08Z

@chr-hertel @Nyholm i am not totally happy with the code - have to rework a bit in the next days - but maybe there is already some feedback about it :)

chr-hertel

Thank you @wachterjohannes for working on this! I think for a first iteration we can go ahead, especially the schema extension with nov release can be a follow up 👍

what's missing from your point of view?

examples/server/elicitation/ElicitationHandlers.php

chr-hertel · 2026-02-01T16:50:14Z

examples/server/elicitation/ElicitationHandlers.php

+                ),
+                'dietary' => new EnumSchemaDefinition(
+                    title: 'Dietary Restrictions',
+                    enum: ['none', 'vegetarian', 'vegan', 'gluten-free', 'halal', 'kosher'],


from DX point of view i think it would be great to support

enum: ['none', 'vegetarian'], // with values being name and value // or enum: ['None' => 'none', 'Vegetarian' => 'vegetarian'], // with index being name and values being value // or enum: Diet::class, // with Diet being a backed enum

follow up tho 👍

examples/server/elicitation/server.php

src/Schema/Elicitation/StringSchemaDefinition.php

src/Schema/Elicitation/PrimitiveSchemaDefinition.php

src/Schema/Elicitation/NumberSchemaDefinition.php

src/Schema/Elicitation/ElicitationSchema.php

src/Schema/Elicitation/EnumSchemaDefinition.php

chr-hertel · 2026-02-01T17:17:37Z

Please have a look at the conformance scenario tools-call-elicitation, elicitation-sep1034-defaults and elicitation-sep1330-enums can be follow-ups if i get it right. requires rebase, but needed anyways.

chr-hertel · 2026-02-01T17:18:33Z

BTW, tested the reservation example with goose - works like a charm! 👍

wachterjohannes · 2026-02-01T20:27:55Z

Follow-ups (Separate PRs)

Conformance Test Scenarios - Listed in conformance-baseline.yml but implementations not yet added to tests/Conformance/server.php:

tools-call-elicitation - Test tool execution flow with elicitation request/response handling
elicitation-sep1034-defaults - Test default value handling in elicitation schemas per SEP-1034 specification
elicitation-sep1330-enums - Test enum field validation and enumNames mapping per SEP-1330 specification

These conformance tests validate elicitation behavior against the MCP specification but aren't blocking since the core feature is working (demonstrated in the examples).

Enum DX Enhancement - Developer experience improvement for enum definitions:

Support multiple enum definition approaches (e.g., associative arrays, value-label pairs)
Make enum field creation more ergonomic and intuitive
Maintain backward compatibility with current string array approach

This was noted as a future improvement in the initial review and doesn't impact current functionality.

wachterjohannes · 2026-02-01T21:00:47Z

@chr-hertel TBH totally forgotten this 😂 Now i am happy with it :)

chr-hertel

Thank you @wachterjohannes!

chr-hertel · 2026-02-13T22:17:58Z

Please sign your commit, and we can merge :)

- Add ElicitAction enum (accept/decline/cancel) - Add schema definitions for elicitation fields (string, number, boolean, enum) - Add ElicitationSchema wrapper for requestedSchema - Add ElicitRequest and ElicitResult for elicitation/create method - Update ClientCapabilities to support elicitation capability - Add elicit() method to ClientGateway - Store client capabilities in session during initialization - Add comprehensive unit tests - Add elicitation example server with book_restaurant, confirm_action, and collect_feedback tools

Move supportsElicitation() capability check from example code to the ClientGateway class as a public method, making it part of the official SDK API. This eliminates code duplication and provides a consistent way for all tools to check client capabilities. - Add ClientGateway::supportsElicitation() public method - Remove duplicate capability check from ElicitationHandlers example - Update all example tools to use SDK method via ClientGateway - Add @author tags to all 6 elicitation schema classes - Remove inline comments from example server (keep header doc) - Add comprehensive elicitation section to examples.md with usage examples, important notes, and tool descriptions

- Add content validation when action is accept - Add default value validation for NumberSchemaDefinition - Mark ElicitResult as final and add missing @author tags - Improve error handling in elicitation examples - Extract AbstractSchemaDefinition to eliminate ~150 lines of duplication

wachterjohannes · 2026-02-14T17:59:59Z

@chr-hertel pushed a signed commit

wachterjohannes mentioned this pull request Jan 26, 2026

Maker as a MCP symfony/maker-bundle#1745

Open

chr-hertel requested changes Feb 1, 2026

View reviewed changes

wachterjohannes force-pushed the elicitation-support branch 3 times, most recently from b345451 to f213574 Compare February 1, 2026 20:25

wachterjohannes force-pushed the elicitation-support branch 3 times, most recently from 68e56b9 to cbee961 Compare February 1, 2026 21:00

wachterjohannes marked this pull request as ready for review February 1, 2026 21:00

wachterjohannes requested review from CodeWithKyrian and Nyholm as code owners February 1, 2026 21:00

wachterjohannes force-pushed the elicitation-support branch from cbee961 to 9af2d4f Compare February 1, 2026 21:03

chr-hertel added this to the 0.4.0 milestone Feb 8, 2026

chr-hertel approved these changes Feb 13, 2026

View reviewed changes

chr-hertel added Server Issues & PRs related to the Server component Schema Issues & PRs related to the Schema component labels Feb 13, 2026

chr-hertel changed the title ~~Add elicitation support for server-to-client user input requests~~ [Server][Schema] Add elicitation support for server-to-client user input requests Feb 13, 2026

wachterjohannes added 3 commits February 14, 2026 18:44

wachterjohannes force-pushed the elicitation-support branch from 9af2d4f to f5c6765 Compare February 14, 2026 17:47

Conversation

wachterjohannes commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Files added

Protocol details

Uh oh!

wachterjohannes commented Jan 24, 2026

Uh oh!

chr-hertel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chr-hertel Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chr-hertel commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chr-hertel commented Feb 1, 2026

Uh oh!

wachterjohannes commented Feb 1, 2026

Follow-ups (Separate PRs)

Uh oh!

wachterjohannes commented Feb 1, 2026

Uh oh!

chr-hertel left a comment

Choose a reason for hiding this comment

Uh oh!

chr-hertel commented Feb 13, 2026

Uh oh!

wachterjohannes commented Feb 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wachterjohannes commented Jan 24, 2026 •

edited

Loading

chr-hertel commented Feb 1, 2026 •

edited

Loading